Kapitel 8 Features von Visual Studio 2005

8.1 Die XML-Dokumentation 

Wenden wir uns zu Beginn dieses Kapitels einem Thema zu, das wir bisher vollkommen ignoriert haben, weil es in keinem direkten Zusammenhang mit der Programmierung steht und deshalb bisher kaum unser Interesse wecken konnte: die XML-basierte Dokumentation. XML ist die Abkürzung für Extensible Markup Language und beschreibt einen Weg, Daten in einem einfachen Textformat so zu speichern, dass sie von jedem Computer gelesen werden können. Im ersten Moment ähnelt XML sehr HTML. Zwischen beiden besteht durchaus eine verwandtschaftliche Beziehung, aber XML ist syntaktisch ausgesprochen streng, während HTML andererseits ziemlich unbeeindruckt Nachlässigkeiten toleriert.

Die XML-Notation ist ziemlich komplex und verhältnismäßig kompliziert. Ich werde Ihnen hier keine Exkursion bieten, um Sie mit den Grundlagen von XML vertraut zu machen. Dafür gibt es inzwischen sehr viele, teilweise auch recht gute Bücher. Nichtsdestotrotz möchte ich Sie an dieser Stelle ermuntern, sich mit XML zu befassen, denn es nimmt eine bedeutende Stellung im .NET Framework ein. Beispielsweise wird es als grundlegendes Datentransportformat benutzt.

In diesem Abschnitt begegnet uns XML zum ersten Mal. Sie können aber sicher sein, es wird uns noch einige Male über den Weg laufen wird. Beispielsweise können nicht nur .NET-Anwendungen mit XML-basierten Dateien konfiguriert werden, sondern die gesamte .NET-Umgebung.

Da uns an dieser Stelle XML zum ersten Mal begegnet, stellt sich auch sofort die Frage, warum XML in .NET einen so hohen Stellenwert hat. Wie Sie wissen, ist .NET plattformunabhängig konzipiert. Um mit einer anderen Plattform für beide Seiten auswertbare Daten austauschen zu können, muss es einen gemeinsamen Nenner geben. Dieser ist ASCII. In ein von beiden Seiten anerkanntes spezifiziertes Format gebracht, sollte ein ASCII-Dokument von beiden Partnern identisch interpretierbar sein. Diese Spezifikation ist XML, die vom W3C (World Wide Web Consortium) definiert ist.

XML definiert die Regeln zum Erstellen maschinen- und menschenlesbarer Dokumente in Form einer Baumstruktur. Gelesen werden XML-Dokumente mit einem Parser, der die in einem XML-Dokument enthaltenen Informationen prüft und den darüber liegenden Schichten einer Anwendung in irgendeiner Form zur Verfügung stellt. Im Internet Explorer ist ein solcher Parser eingebaut.

8.1.1 XML-Kommentare 

In Visual Basic 2005 lässt sich der Code bereits innerhalb des Code-Editors dokumentieren. Dazu werden XML-Tags in spezielle Kommentarfelder des Quellcodes unmittelbar vor dem Codeblock eingefügt, auf den sie sich beziehen. Auf diese Weise können Typen wie Klassen, Enumerationen, Delegaten, Schnittstellen und Strukturen sowie deren Eigenschaften, Felder, Methoden, Ereignisse usw. beschrieben werden.

Eingeleitet werden die Kommentarfelder mit drei einfachen Anführungszeichen. Wenn Sie den Cursor vor das zu dokumentierende Element positionieren und die drei einleitenden Schrägstriche in den Code vor eine Klassendefinition schreiben, wird der folgende XML-Kommentar automatisch ergänzt:

Zwischen dem ein- und ausleitenden Tag können Sie eine Beschreibung eintragen, die später vom zu generierenden XML-Dokument übernommen wird. Zudem wird die Beschreibung in IntelliSense und im Objektbrowser angezeigt. Die Beschreibung zwischen <summary> und </summary> sollte also nicht zu lang ausfallen. Für ausführlichere Beschreibungen steht Ihnen mit <remarks> ein geeigneteres Tag zur Verfügung.

Bei dem ausgefeilten Automatismus und der hervorragenden Unterstützung des Entwicklers wundert es eigentlich nicht, dass von Visual Studio 2005 berücksichtigt wird, wenn ein Klassenmitglied eine nicht leere Parameterliste aufweist oder gar einen Rückgabewert liefert. Beispielsweise wird der automatisch eingefügte XML-Kommentar der Methodendefinition

lauten:

Sie können erkennen, dass über <summary> hinaus noch weitere vordefinierte XML-Dokumentationstags angeboten werden. Das Attribut name des <param>-Tags enthält den Bezeichner des Parameters. Zwischen dem ein- und ausleitenden Tag dürfen Sie auch eine zusätzliche Beschreibung eintragen. Diese wird zwar vom späteren XML-Dokument übernommen und im Objektbrowser angezeigt, allerdings nicht in IntelliSense. <returns> dient zur Beschreibung des Rückgabewertes. Für dieses Tag gilt hinsichtlich der Anzeige dasselbe wie für <param>.

Sehen wir an dieser Stelle einmal einen etwas aufwändigeren XML-Kommentar sowie dessen Auswirkungen an.

Mit dem Objektbrowser können Sie Objekte (Namespaces, Klassen, Strukturen, Schnittstellen, Typen, Enumerationen usw.) und ihre Member (Eigenschaften, Methoden, Ereignisse, Variablen, Konstanten, Enumerationselemente) aus verschiedenen Komponenten suchen und überprüfen. Bei diesen Komponenten kann es sich um Projekte in der Projektmappe, um referenzierte Komponenten innerhalb dieser Projekte und um externe Komponenten handeln. Sie öffnen den Objektbrowser über das Menü Ansicht oder die entsprechende Schaltfläche in der Symbolleiste von Visual Studio. Im Objektbrowser wollen wir uns nun die Ausgabe der Methode TestMethod ansehen.

Hier klicken, um das Bild zu Vergrößern

Abbildung 8.1     Ausgabe des XML-Kommentars im Objektbrowser

Ich glaube, dass Sie auch ohne eine langatmige Beschreibung erkennen können, welche Bereiche den einzelnen Tags zugeordnet werden. Im Code-Editor hingegen wird nur die Beschreibung angezeigt, die hinter <summary> angegeben ist (siehe Abbildung 8.2).

Hier klicken, um das Bild zu Vergrößern

Abbildung 8.2     IntelliSense der Methode »TestMethod«

8.1.2 Die XML-Kommentar-Tags 

Ich habe Ihnen bisher einige, aber nicht alle Tags vorgestellt, die der XML-Dokumentation dienlich sind. In der folgenden Tabelle stelle ich Ihnen alle der Übersicht halber vor.

8.1.3 Generieren der XML-Dokumentationsdatei 

Die Typen und deren Member mit XML-Kommentar zu versehen reicht zwar schon aus, um im Objektbrowser oder in der IntelliSense-Unterstützung den Benutzer mit grundlegenden Informationen zu versorgen, aber damit wird nicht sofort ein XML-Dokument erzeugt, das sich beispielsweise zu einer Integration in einer Hilfe eignet und durchaus auch noch weitere Informationen bereitstellen kann.

Der VB-Compiler stellt zur Erzeugung eines XML-Dokuments mit /doc einen eigenen Compilerschalter bereit. Sie brauchen allerdings nicht an der Konsole zu kompilieren, Sie können den Schalter auch direkt im Projekt einstellen. Öffnen Sie dazu das Projekteigenschaftsfenster. Dazu markieren Sie das Projekt im Projektmappen-Explorer und öffnen das Kontextmenü. Das Eigenschaftsfenster finden Sie unter Eigenschaften. Am linken Rand sind mehrere Laschen gruppiert, von denen Sie auf Kompilieren klicken (siehe Abbildung 8.3). In der nun angezeigten Registerkarte setzen Sie ein Häkchen neben XML-Dokumentationsdatei generieren. In der Regel ist das Häkchen bereits per Vorgabe gesetzt. Damit ist alles Notwendige erledigt. Die Vorgabe des Ausgabeordners und den Bezeichner der XML-Dokumentationsdatei können Sie im Bedarfsfall auch ändern.

Hier klicken, um das Bild zu Vergrößern

Abbildung 8.3     Einstellen der Erzeugung eines XML-Dokumentationsdokuments

Wir sollten auch einen Blick in das erzeugte Dokument werfen. Das gesamte Dokument wird in ein <doc> gefasst. <doc> umfasst neben der Bekanntgabe des Dokumentationsnamens in <assembly> im Bereich <members> auch alle Tags, die wir im Code-Editor aufgeführt haben.